---
order: 5
title: 精灵图集
type: 图形
group: 2D
label: Graphics/2D
---

## 概述
[SpriteAtlas](/apis/core/#SpriteAtlas) 是用于优化2D渲染性能的图集资源，通过合并多个精灵纹理实现**批量绘制**，核心优势包括：

✅ **性能提升**：减少DrawCall数量，提升渲染效率  
✅ **资源优化**：合并碎片化纹理，降低网络请求次数  
✅ **内存管理**：减少纹理切换带来的GPU内存开销

## 编辑器使用

### 创建图集资源
1. **路径**：资产面板 > 右键菜单 > `创建` > `精灵图集`
2. **操作**：创建后生成空白图集资产，可在检查器配置属性

<Image src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*W-HZSrvAiG8AAAAAAAAAAAAADjCHAQ/original" alt="创建精灵图集操作示意图" style={{zoom:"50%"}} />

### 管理精灵成员

#### 添加精灵
| 操作方式                      | 步骤说明                                                                 |
|------------------------------|------------------------------------------------------------------------|
| **通过精灵资产添加**          | 1. 选择目标精灵 2. 检查器面板 > `从属关系` > 选择目标图集          |
| **通过图集资产批量添加**      | 1. 选择目标图集 2. 检查器面板 > 点击`添加精灵`（支持文件夹批量操作）|

<Image 
  src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*G_utQZfPYPoAAAAAAAAAAAAADjCHAQ/original" 
  alt="通过精灵资产添加至图集示意图"
  style={{zoom:"67%"}} 
/>

#### 移除精灵
| 操作方式                      | 步骤说明                                                                 |
|------------------------------|------------------------------------------------------------------------|
| **通过精灵资产移除**          | 检查器面板 > `从属关系` > 点击移除图标                                  |
| **通过图集资产移除**          | 检查器面板 > 精灵列表 > 定位目标精灵 > 点击移除图标                     |

### 图集配置参数

#### 打包设置
<Image 
  src="https://gw.alipayobjects.com/zos/OasisHub/81a2044b-c1b7-449d-96cf-1e098b72a1be/image-20231208165843716.png" 
  alt="图集打包参数配置界面"
  style={{zoom:"50%"}} 
/>

| 参数                | 说明                                                                 | 取值范围           |
|--------------------|--------------------------------------------------------------------|------------------|
| **纹理最大宽度**    | 输出纹理宽度限制                                                       | (1, 2048]        |
| **纹理最大高度**    | 输出纹理高度限制                                                       | (1, 2048]        |
| **边缘填充**        | 打包精灵的边缘填充宽度                                        | ≥0               |
| **允许旋转**        | 启用精灵旋转提升空间利用率（实验性功能，暂未开放）                            | `true`/`false`   |
| **空白裁减**        | 自动移除透明区域优化空间利用（实验性功能，暂未开放）                          | `true`/`false`   |

<Callout type="warning">**超限警告**：若打包后尺寸超过限制，需调整最大宽高或重新编排精灵。</Callout>

#### 纹理参数设置
<Image 
  src="https://gw.alipayobjects.com/zos/OasisHub/1f4302b8-d485-4d3e-b508-36b570f5a883/image-20231208165430415.png" 
  alt="图集纹理参数配置界面"
  style={{zoom:"50%"}} 
/>

| 参数                   | 可选值                                                                 |
|-----------------------|----------------------------------------------------------------------|
| **Wrap Mode U/V**     | `Clamp`（截取）/ `Repeat`（重复）/ `Mirror`（镜像）                   |
| **Filter Mode**       | `Point`（点过滤）/ `Bilinear`（双线性）/ `Trilinear`（三线性）        |
| **Aniso Level**       | 各向异性过滤等级（1-16）                                              |
| **Generate Mipmaps**  | 是否生成Mipmap链                                                      |

## 脚本开发指南

### 命令行打包工具
```bash
# 全局安装工具包
npm i @galacean/tools-atlas -g

# 执行打包（示例：输入目录为assets，输出名为ui_atlas）
galacean-tool-atlas p assets -o ui_atlas
```

| 属性           | 解释                                         |
| -------------- | -------------------------------------------- |
| f/format       | 打包输出的精灵图集格式 (默认: "galacean")    |
| o/output       | 打包输出的精灵图集文件名 (默认: "galacean")  |
| a/algorithm    | 打包精灵图集的算法 (默认: "maxrects")        |
| ar/allowRotate | 打包精灵图集是否支持旋转 (默认: false)       |
| p/padding      | 图集中每个精灵和这个精灵边框的距离 (默认: 1) |
| mw/maxWidth    | 最后打包出的精灵图集的最大宽度 (默认: 1024)  |
| mh/maxHeight   | 最后打包出的精灵图集的最大高度 (默认: 1024)  |
| s/square       | 强制打包成正方形 (默认: false)               |
| pot            | 宽高强制打包成 2 的幂 (默认: false)          |

> 📘 [完整参数文档](https://github.com/galacean/tools/blob/main/packages/atlas/README.md)

### 运行时加载使用
```typescript
// 加载图集资源
engine.resourceManager.load<SpriteAtlas>({
  url: "https://cdn.com/ui_atlas.atlas",
  type: AssetType.SpriteAtlas
}).then((atlas) => {
  // 获取全部精灵
  const allSprites = atlas.sprites;

  // 按名称精确查询
  const heroSprite = atlas.getSprite("hero_idle"); 

  // 批量查询同名精灵
  const duplicateSprites = atlas.getSprites("coin", []); 
});
```

<Callout type="info">上传图集图片和图集文件至 CDN 同一目录下，例如文件和图片的地址应分别为 `https://*cdnDir*/*atlasName*.atlas` 和 `https://*cdnDir*/*atlasName*.png`。</Callout>

## 最佳实践

### 图集优化技巧
1. **尺寸规划**：控制打包资源尺寸，预设合理最大宽高（推荐1024x1024），避免纹理尺寸超标
2. **预览调整**：通过`打包并预览`功能查看利用率（建议≥80%）

<Image 
  src="https://mdn.alipayobjects.com/huamei_w6ifet/afts/img/A*lyhRSY63HJgAAAAAAAAAAAAADjCHAQ/original" 
  alt="图集利用率预览示意图"
/>

## API参考
| 核心类          | 关键方法/属性                     | 说明                       |
|----------------|---------------------------------|--------------------------|
| `SpriteAtlas`  | `sprites: Sprite[]`            | 获取图集内全部精灵         |
|                | `getSprite(name: string)`      | 按名称获取单个精灵（若存在同名，返回第一个）         |
|                | `getSprites(name: string)`     | 按名称获取所有同名精灵        |